home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / hpgn12.zip / DEMO.MAC < prev    next >
Text File  |  1994-09-06  |  11KB  |  298 lines
  1.  
  2. .rem(=============================================================)
  3. .rem(DEMO.MAC)
  4. .rem( )
  5. .rem(Created by the HelpGen Help Generator, version 1.20)
  6. .rem(Copyright ⌐ 1994 by Rimrock Software)
  7. .rem(All rights reserved.)
  8. .rem(=============================================================)
  9.  
  10. .start(main,Contents,DEMO.BMP,Demo Help Contents)
  11. .top(Help)
  12. .top(Table of Contents)
  13. .n
  14. The DEMO help file example makes use of many of the HelpGen 
  15. .p(macro,macros) and .p(rtfcmds,RTF commands) that are documented with HelpGen..n
  16. .in
  17. ##.j(planhlp,Planning Your Help File)
  18. ##.j(createmac,Creating the Macro File)
  19. ##.j(usemacros,Using HelpGen Macros and RTF Commands)
  20. ##.j(createhpj,Creating the Project File)
  21. ##.j(creatertf,Generating the RTF File)
  22. ##.j(createhlp,Generating the Help File)
  23. ##.j(testhlp,Testing the Help File).n.n
  24. .bj(glossary,DEMO.BMP)   .b(Glossary).n
  25. .un
  26. .n
  27. If you are unfamiliar with how Windows Help works, choose
  28.  .b(Help | How To Use Help) from the Help menu now.
  29. .end
  30.  
  31. .ent(icon,Information,Demo )
  32. This icon topic .b(MUST) be present.  It is activated by clicking 
  33. on the icon in the Table of Contents.  You may place your own 
  34. text here..n
  35. \qc
  36. .box
  37. \brdrth
  38. HelpGen and this demo are \'a9 1994 Rimrock Software.  All rights 
  39. reserved.
  40. .bend
  41. \ql
  42. .end
  43.  
  44. .ent(planhlp,Planning Your Help File, )
  45. Planning the layout and contents of the help file is probably 
  46. the most important part of creating on-line help.  A poorly 
  47. conceived and implemented help file is almost worthless to a user.  
  48. They may not be able to find anything they are looking for in the 
  49. help file, and if they do find the correct item, it may not help 
  50. with their problems..n.n
  51. This part of help file generation doesn't have much to do with the 
  52. actual mechanics of creating the help file, but it .b(is) important, 
  53. nevertheless.  Some basic steps in planning a help file are detailed 
  54. below..n
  55. .in
  56. #b(Outline the Help Subjects)  Plan to have a few major sections, and 
  57. many minor sections.  For instance, one way to organize is 
  58. to use the basic outline of your user manual.  Another way is shown below:.n.n
  59. \tab\tab .b(Introduction).n
  60. \tab\tab .b(How To).n
  61. \tab\tab .b(Menu Items).n
  62. \tab\tab\tab File.n
  63. \tab\tab\tab\tab Open.n
  64. \tab\tab\tab\tab Close.n
  65. \tab\tab\tab\tab Exit.n
  66. \tab\tab\tab Edit.n
  67. \tab\tab\tab\tab Cut.n
  68. \tab\tab\tab\tab Copy.n
  69. \tab\tab\tab\tab Paste.n.n
  70. \tab This outline can go down as many levels as you want, but anything 
  71. more than about 4 levels is too complicated for a normal user to 
  72. navigate.  Once you have this basic outline, you essentially have 
  73. each of the topics that will be discussed in the help file.  Each 
  74. level of the outline except the lowest level corresponds to a single 
  75. display page in the help file.  Each topic on the lowest level of the 
  76. outline corresponds to a single display page in the help file..n.n
  77. \tab Continuing with our example above, then, the Table of Contents 
  78. page would contain the Introduction, How To and Menu Items topics.  
  79. If a user clicked on Menu Items, they would move to a page titled 
  80. Menu Items, which contains File and Edit topics.  Clicking on the 
  81. File item, they would move to a page containing the Open, Close and 
  82. Exit topics.  And finally, clicking on Open would move to a page that 
  83. explains the File | Open menu item..n
  84. #b(Create Topic Tags)  Each item on each level of the outline should 
  85. have a single word 'tag' that can be used to reference it to.  Go 
  86. through the outline and create a tag for each outline item.  We will 
  87. use these when we add the topics to the macro file..n.n
  88. \tab\tab .b(Introduction) - intro.n
  89. \tab\tab .b(How To) - howto.n
  90. \tab\tab .b(Menu Items) - menuitems.n
  91. \tab\tab\tab File - file.n
  92. \tab\tab\tab\tab Open - fileopen.n
  93. \tab\tab\tab\tab Close - fileclose.n
  94. \tab\tab\tab\tab Exit - fileexit.n
  95. \tab\tab\tab Edit - edit.n
  96. \tab\tab\tab\tab Cut - editcut.n
  97. \tab\tab\tab\tab Copy - editcopy.n
  98. \tab\tab\tab\tab Paste - editpaste.n
  99. #b(Flesh Out the Outline)  What you are really doing is writing a user 
  100. manual that will be read on-line in a non-linear (hypertext) fashion.  
  101. Much of what you would normally say in a manual will be included in 
  102. the on-line help..n.n
  103. \tab Write explanations for each of the items on the lowest level of 
  104. your outline.  Use graphics (\'2eBMP files) and/or examples liberally 
  105. to explain the subject (a picture really .i(is) worth 1000 words)..n
  106. #b(Mark Definitions)  When you have completely written all the text 
  107. for your help file, go back and circle the terms that you think 
  108. the user will have trouble with, and that need to be defined.  These 
  109. terms will form the basis of your glossary.  The first time such a 
  110. term is encountered in .i(any) topic, it should be marked with a 
  111. \'2ep or \'2ep1 and should be explained in a \'2epent entry.  Create 
  112. a topic tag for each of the terms..n
  113. #b(Create the Macro File)  You are now ready to create and edit a 
  114. macro file for your on-line help..n
  115. .un
  116. .end
  117.  
  118. .ent(createmac,Creating the Macro File, )
  119. Now that you have your help topics outlined and fleshed out, you can 
  120. create and edit a macro file for your help..n
  121. .in
  122. #n(1)Continuing with the example we started in .b(Planning Your Help File,) 
  123. let's create an initial macro file.  Click on .b(File | Open Macro File) 
  124. and type in 'MYHELP' for a file name.  HelpGen will ask if you wish 
  125. to create this file.  Click on the 'Yes' button and MYHELP will be 
  126. created..n
  127. #n(2)Now let's do some editing on this file.  Click on .b(Edit | Macro File.)  
  128. The text editor should appear, with the newly created MYHELP.MAC 
  129. displayed in it.  Let's use the DEMO\'2eBMP file for the icon, 
  130. change the table of contents header from xxxx to Table of Contents 
  131. and add the first level of our outline to the table of contents 
  132. topic:.n.n
  133. .[
  134. \'2erem(=============================================================).n
  135. \'2erem(MYHELP.MAC).n
  136. \'2erem( ).n
  137. \'2erem(Created by the HelpGen Help Generator, version 1.20).n
  138. \'2erem(Copyright \'a9 1994 by Rimrock Software).n
  139. \'2erem(All rights reserved.).n
  140. \'2erem(=============================================================).n
  141. .n
  142. \'2estart(main,Contents,DEMO\'2eBMP,Table of Contents).n
  143. \'2etop(Help).n
  144. \'2etop(Table of Contents).n
  145. .n
  146. \'2es.n
  147. \'2ein.n
  148. \'23\'23\'2ej(intro,Introduction).n
  149. \'23\'23\'2ej(howto,How To).n
  150. \'23\'23\'2ej(menuitems,Menu Items).n
  151. \'2eun.n
  152. \'2eend.n
  153. .n
  154. \'2eent(icon,Information,Icon ).n
  155. This icon topic \'2eb(MUST) be present.  It is activated by clicking 
  156. on the icon in the Table of Contents.  You may place your own 
  157. text here..n
  158. \'2eend.n
  159. .n
  160. \'2eend_file.n.n
  161. .]
  162. Note that we dress up the topics by indenting them (\'2ein and \'2eun) 
  163. and by putting a bullet in front of them (\'23\'23).  We shouldn't 
  164. compile this until we add the entries for the three jumps we just added:.n.n
  165. .[
  166. \'2estart(main,Contents,DEMO\'2eBMP,Table of Contents).n
  167. \'2etop(Help).n
  168. \'2etop(Table of Contents).n
  169. .n
  170. \'2es.n
  171. \'2ein.n
  172. \'23\'23\'2ej(intro,Introduction).n
  173. \'23\'23\'2ej(howto,How To).n
  174. \'23\'23\'2ej(menuitems,Menu Items).n
  175. \'2eun.n
  176. \'2eend.n
  177. .n
  178. \'2eent(icon,Information,Icon ).n
  179. This icon topic \'2eb(MUST) be present.  It is activated by clicking 
  180. on the icon in the Table of Contents.  You may place your own 
  181. text here..n
  182. \'2eend.n.n
  183. \'2eent(intro,Introduction, ).n
  184. \'2eend.n.n
  185. \'2eent(howto,How To, ).n
  186. \'2eend.n.n
  187. \'2eent(menuitems,Menu Items, ).n
  188. \'2eend.n
  189. .n
  190. \'2eend_file.n.n
  191. .]
  192. Now we can compile it if we want to, but let's continue.  Next, we 
  193. add the second level of the outline.  In this case, it means adding 
  194. to the Menu Items topic, and adding new topics for the third 
  195. outline level:.n.n
  196. .[
  197. \'2eent(menuitems,Menu Items, ).n
  198. \'2ein.n
  199. \'23\'23\'2ej(file,File).n
  200. \'23\'23\'2ej(edit,Edit).n
  201. \'2eun.n
  202. \'2eend.n.n
  203. \'2eent(file,File Menu,The ).n
  204. \'2eend.n.n
  205. \'2eent(edit,Edit Menu,The ).n
  206. \'2eend.n
  207. .n
  208. \'2eend_file.n.n
  209. .]
  210. We continue to add new jumps and new topics until we reach the last 
  211. level of the outline, where all the text will be entered.
  212. .end
  213.  
  214. .ent(usemacros,Using HelpGen Macros and RTF Commands, )
  215. If you have looked at .b(Creating the Macro File,) you will see that 
  216. we have already used many of the basic HelpGen macros.  The 
  217. remaining macros and RTF commands are used to primarily dress up 
  218. the help file, to make it more interesting and easier to use 
  219. for the user..n.n
  220. \li1050\ri1050 For instance, we just used the \\li and \\ri RTF 
  221. commands to squish this paragraph down.  This makes it stand out from 
  222. surrounding text..n
  223. \li180\ri180
  224. .box
  225. \brdrsh
  226. .b(NOTE:)  Another way to make text stand out is to place it in a box (\'2ebox 
  227. and \'2ebend macros).  This is the .i(most) common method used in user 
  228. manuals to highlight important information.  This particular box is a 
  229. single line box with shading enabled.
  230. .bend
  231. .end
  232.  
  233. .ent(createhpj,Creating the Project File, )
  234. When we are ready to compile our help file, we will need a project 
  235. file to tell the compiler how to compile it.  Follow these steps 
  236. when creating a project file:.n
  237. .in
  238. #n(1)Select the .b(Options | Project File) menu item.  Make sure 
  239. that all the listed options are set the way you want them.  Keep 
  240. in mind that in the shareware version of HelpGen, you can't change 
  241. the copyright notice..n
  242. #n(2)Select the .b(Build | Project File) menu item.  Answer 'Yes' 
  243. to the question and a project file will be built for you..n
  244. .un
  245. .end
  246.  
  247. .ent(creatertf,Generating the RTF File, )
  248. When you have finished editing the macro file, you will want to 
  249. create an RTF file from the macro file.  Select the 
  250. .b(Build | RTF File) menu item to perform this step.
  251. .end
  252.  
  253. .ent(createhlp,Generating the Help File, )
  254. When the RTF file has been built, HelpGen will enable the 
  255. generation of a help file.  Select the .b(Build | HLP File) menu 
  256. item and HelpGen will invoke the help compiler that you have 
  257. told it to use (see .b(Options | Directories)).
  258. .end
  259.  
  260. .ent(testhlp,Testing the Help File, )
  261. After the help compiler generates a help file for you (assuming 
  262. that it did so with no errors), you can test the file.  To do this, 
  263. select the .b(Test) menu item.  HelpGen will invoke the WinHelp 
  264. help engine, using your help file.  You can then proceed with the testing..n
  265. .end
  266.  
  267. .ent(glossary,Glossary, )
  268. .in
  269. .p(macro,Macro).n
  270. .p(project,Project).n
  271. .p1(RTF).n
  272. .p(rtfcmds,RTF Commands).n
  273. .un
  274. .end
  275.  
  276. .pent(macro,macro, )
  277. The replacement of a long series of .p1(RTF) commands with a single 
  278. command word and (optional) series of arguments.
  279. .end
  280.  
  281. .pent(project,project, )
  282. A file with the extension .HPJ, that contains options that 
  283. specifies how a help file is to be built.  Required by the 
  284. help compiler.
  285. .end
  286.  
  287. .pent(RTF,RTF, )
  288. Rich Text Format, a standard text file formatting standard. An 
  289. RTF file consists of .p(rtfcmds,RTF commands) and normal text.
  290. .end
  291.  
  292. .pent(rtfcmds,RTF commands, )
  293. Special commands in an .p1(RTF) file that describe how text is to be 
  294. displayed.  These commands start with a backslash (\\) character.
  295. .end
  296.  
  297. .end_file
  298.